home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / installed_progs / dev / flexcat / doc / flexcat_español.doc < prev    next >
Encoding:
Text File  |  1994-05-31  |  36.7 KB  |  847 lines
  1. Documentación de FlexCat V1.3
  2. *****************************
  3.  
  4.    Este fichero describe la Utilización de Flexcat V1.3, un programa que
  5. genera catálogos, y el fuente para manejarlos.  FlexCat opera de forma
  6. parecida a como lo hacen CatComp y KitCat, pero se diferencia de ellos
  7. en que genera el código fuente que quieras.  Esto se hace usando las
  8. Descripciones de Fuente, las cuales son un patrón del código que se
  9. va a generar. Se pueden editar, y por tanto, adaptar a cualquier lenguaje
  10. de programación o necesidades individuales. (¡Eso espero!)
  11.  
  12. Derechos de Autor y demás materia legal
  13. ***************************************
  14.  
  15.      Copyright (C) 1993    Jochen Wiedmann
  16.              Am Eisteich 9
  17.              72555 Metzingen (Deutschland)
  18.              Tel. 07123 / 14881
  19.              Internet: wiedmann@mailserv.zdv.uni-tuebingen.de
  20.  
  21.    Se garantiza el permiso para hacer y distribuir copias intactas y
  22. modificadas de este manual y el programa FlexCat siguiendo los términos de
  23. "GNU General Public License" simpre que se preserven en todas las copias
  24. las notas de Derechos de Autor y ésta nota de permiso, además de que se
  25. distribuya tambien la "GNU General Public License" (en el fichero
  26. COPYING).
  27.  
  28.    El autor no da garantía alguna de que el programa que se describe en
  29. esta documentación y los resultados producidos por él sean correctos. El
  30. autor no se puede responsabilizar de cualquier daño resultado del uso de
  31. este software.
  32.  
  33. Vistazo
  34. *******
  35.  
  36.    A partir del Workbench 2.1 el Amiga ofrece un sistema bastante cómodo
  37. para usar programas en diferentes idiomas: La locale.library. (A esto se
  38. le llama localización, que es para lo que vale el nombre.)
  39.  
  40.    La idea es sencilla: Eliges un idioma, el castellano la mayoría de los
  41. casos, y escribes tu programa de la misma forma que que lo hacías sin
  42. localización a excepción de que las cadenas constantes se substituyen por
  43. ciertas llamadas a función. Otra llamada a una función permite que los
  44. usuarios elijan otro idioma al iniciar el programa. (Esta última llamada
  45. lee un fichero externo, el llamado catálogo, y hace que se lean las
  46. cadenas o textos del catálogo en vez de las predefinidas).
  47.  
  48.    Estos catálogos son independientes del programa. Todo lo que necesitas
  49. para añadir otro idioma es crear un nuevo catálogo, lo cual se puede
  50. hacer en cualquier momento sin falta de modificar el programa.
  51.  
  52.    Sin embargo hay tareas adicionales para el programador: Necesita crear
  53. los catálogos, las cadenas predefinidas, y algo de código fuente para
  54. manejarlas. (Las funciones que se mencionaron antes). Flexcat está
  55. diseñado para hacer esto de una forma sencilla y casi automática sin
  56. perder flexibilidad, especialmente al crear el código fuente. Lo veremos
  57. más claro con un ejemplo:
  58.  
  59.    Supongamos que queremos escribir un HolaMundoLocal.c. Nuestro programa
  60. final quedaría como:
  61.       #include <stdio.h>
  62.       #include <stdlib.h>
  63.       #include <HolaMundoLocal_Cat.h>    /* ¡Debes incluirlo! */
  64.       #include <clib/exec_protos.h>
  65.      
  66.       struct Library *LocaleBase;
  67.      
  68.       void main(int argc, char *argv[])
  69.       { /*    Abre la librería tú mismo aunque el compilador permita la    */
  70.         /*  apertura automática. NO salgas si falla OpenLibrary, en ese */
  71.         /*  caso usaremos las cadenas internas.                */
  72.         LocaleBase = OpenLibrary("locale.library", 38);
  73.      
  74.         OpenHolaMundoLocalCatalog(NULL, NULL);
  75.      
  76.         printf("%s\n", GetHolaMundoLocalString(msgHola));
  77.      
  78.         CloseHolaMundoLocalCatalog();
  79.         if (LocaleBase)
  80.            CloseLibrary(LocaleBase);
  81.       }
  82.  
  83. Fíjate que es casi igual que el HolaMundo.c original a excepción de que
  84. sustituye la cadena "¡Hola mundo!" por una llamada a una función y que
  85. contiene algunas inicializaciones adicionales.
  86.  
  87.    El programa anterior usa la constante msgHola. La llamada a
  88. GetHolaMundoLocalString hace la sustitución por la cadena
  89. correspondiente. Estas constantes y cadenas están definidas en el fichero
  90. Descripción de Catálogo. (see Descripcion de catalogo).  Siempre se
  91. empieza creando un fichero de ese tipo, el HolaMundoLocal.cd, que podría
  92. ser como el siguiente:
  93.       ; Por supuesto, se permiten comentarios. Toda línea que empieze
  94.       ; con un punto y coma se supone un comentario.
  95.       ;
  96.       ; El idioma de las cadenas internas:
  97.       #language español
  98.       ;
  99.       ; Versión del catálogo, se usa en la llamada a Locale/OpenCatalog().
  100.       ; Esto es diferente a Exec/OpenLibrary(): 0 significa cualquier
  101.       ; versión de catálogo, ¡otro, significa coincidir exactamente!
  102.       #version 0
  103.       ;
  104.       ; Esto define una cadena y el ID que permite usarla.
  105.       ; El número 4 indica que la cadena no debe tener menos de 4
  106.       ; caracteres.
  107.       msgHola (/4/)
  108.       ¡Hola mundo!
  109.  
  110.    Usando FlexCat puedes crear otros dos ficheros a partir de la
  111. descripción de catálogo: el fichero include HolaMundoLocal_Cat.h que
  112. define las constantes (ID), y el HolaMundoLocal_Cat.c, el cual contiene un
  113. vector con las cadenas y las funciones OpenHolaMundoLocalCatalog(),
  114. GetHolaMundoLocalString() y CloseHolaMundoLocalCatalog().  No
  115. necesitas saber como son, sólo cómo usarlas.¡ Especialmente si no
  116. necesitas saber nada sobre la locale.library!
  117.  
  118.    En cambio, podrías estar interesado en el funcionamiento de estos
  119. ficheros o incluso podrías querer cambiarlos. Esta es la diferencia entre
  120. FlexCat y los demás generadores de catálogos: FlexCat no necesita usar un
  121. formato interno especial para la creación de esos ficheros. En su lugar
  122. usa ficheros externos, las Descripciones de fuente. Esto permite, por
  123. ejemplo, el uso de catálogos con AmigaDOS 2.0.  see Descripcion fuente. Si
  124. usas las descripciones de código fuente de la distribución de FlexCat
  125. puedes crear los ficheros fuente con los siguientes comandos:
  126.          FlexCat HolaMundoLocal.cd HolaMundoLocal_Cat.c=C_c_V21
  127.          FlexCat HolaMundoLocal.cd HolaMundoLocal_Cat.h=C_h.sd
  128.  
  129.    Una vez que tengas tu programa listo usarás FlexCat de nuevo para crear
  130. los ficheros Traducción de Catálogo, uno para cada idioma que quieras
  131. soportar. (Excepto para español, que es interno).  See Traduccion de
  132. catalogo. Vamos a crear una traducción de catálogo en inglés.
  133.          FlexCat HolaMundoLocal.cd NEWCTFILE English.ct
  134.  
  135. Este fichero sería como sigue:
  136.       ## version
  137.       ## language
  138.       ## codeset 0
  139.       ; Por supuesto, se permiten comentarios. Toda línea que empieze
  140.       ; con un punto y coma se supone un comentario.
  141.       ;
  142.       ; El idioma de las cadenas internas:
  143.       ;
  144.       ; Versión del catálogo, se usa en la llamada a Locale/OpenCatalog().
  145.       ; Esto es diferente a Exec/OpenLibrary(): 0 significa cualquier
  146.       ; versión de catálogo, ¡otro, significa coincidir exactamente!
  147.       ;
  148.       ; Esto define una cadena y el ID que permite usarla.
  149.       ; El número 4 indica que la cadena no debe tener menos de 4
  150.       ; caracteres.
  151.       msgHola
  152.      
  153.       ; ¡Hola mundo!
  154.  
  155. Como ves, se parece mucho a la descripción de catálogo. FlexCat incluye
  156. los comentarios de la descripción de catálogo, incluso los que no tienen
  157. mucho sentido: Fíjate en el comentario de la longitud de cadena, el cual
  158. no debería aparecer ahí ya que esa información sólo debe estar en la
  159. descripción de catálogo. Todo lo que tienes que hacer ahora es rellenar
  160. la información sobre la versión (se espera una cadena típica de versión
  161. como $VER: English.catalog 1.0 (22.05.94), el idioma de la traducción de
  162. catálogo (aquí para inglés sería english), el codeset (que debería
  163. ser siempre 0 por ahora, para más detalles mira en Locale/Catalogs() ) y,
  164. por supuesto, las propias cadenas. FlexCat incluye las cadenas originales
  165. en forma de comentarios de forma que siempre sepas que es lo que tienes que
  166. poner.
  167.  
  168.    Finalmente, creas los catálogos con comandos como:
  169.          FlexCat HolaMundoLocal.cd English.ct CATALOG English.catalog
  170.  
  171. Fíjate que ¡no necesitas el programa o los ficheros fuentes creados con
  172. FlexCat para los catálogos! Puedes crear nuevos catálogos en cualquier
  173. momento. Es usual ofrecer distribuciones con un fichero CatalogoNuevo.ct,
  174. de forma que los usuarios puedan crear sus propios catálogos.
  175.  
  176.    Pero, ¿qué ocurre si cambias el programa más tarde? Simplemente edita
  177. la descripción de catálogo y usa FlexCat para actualizar las traducciones
  178. de catálogo:
  179.          FlexCat HolaMundoLocal.cd English.ct NEWCTFILE English.ct
  180.  
  181. Todo lo que tienes que hacer ahora es introducir las nuevas cadenas si es
  182. necesario.
  183.  
  184. Instalación
  185. ***********
  186.  
  187.    FlexCat está escrito en Ansi-C puro (excepto la localización), por
  188. ello, debería correr en cualquier Amiga y con suerte en otras máquinas
  189. después de compilarlo. (La localización queda como comentarios en ese
  190. caso). Esto tambien es aplicable a los programas: Flexcat está escrito
  191. utilizándose a sí mismo. Todas las descripciones de fuente distribuidas
  192. deberían crear programas que se ejecuten en cualquier Amiga, e incluso en
  193. cualquier máquina. (Por supuesto, debes asegurarte de que la variable
  194. LocaleBase tiene un valor NULL en este último caso). Sin embargo, la
  195. localización sólo es posible a partir del Workbench 2.1 porque la
  196. locale.library no estaba disponible antes.
  197.  
  198.    No es imposible ofrecer localización sin la locale.library: Los
  199. ficheros de descripción de fuente C_c_V20.sd y C_h_V20.sd ofrecen un
  200. ejemplo en el que se usa la iffparse.library para sustituir la
  201. locale.library si ésta no está disponible. Esto permite
  202. Localización en el Workbench 2.0. See C.
  203.  
  204.    Instalar FlexCat es simple: Copia el programa en un directorio en tu
  205. camino de búsqueda y elige un lugar para las descripciones de fuente que
  206. necesites. (Éstas son los ficheros que tienen nombres de la forma
  207. xx_yy.sd, donde xx es el lenguaje de programación). Si quieres
  208. usar FlexCat en otro idioma distinto del inglés tambien necesitas copiar
  209. los catálogos correspondientes. Ej. para el castellano debes copiar
  210. Catalogs/español/FlexCat.catalog en
  211. Locale:Catalogs/español/FlexCat.catalog o
  212. PROGDIR:Catalogs/español/FlexCat.catalog, donde PROGDIR: es el
  213. directorio del programa FlexCat. See Usando fuentes FlexCat.
  214.  
  215. Llamando a FlexCat desde el CLI
  216. *******************************
  217.  
  218.    Flexcat es un programa basado en el CLI y no funciona desde el Workbench.
  219. Su sintaxis de llamada es
  220.          FlexCat CDFILE/a,CTFILE,CATALOG/k,NEWCTFILE/k,SOURCES/m
  221.  
  222. donde el significado de los argumentos es
  223. CDFILE
  224.      es el nombre de la descripción de catálogo a leer. Siempre es
  225.      necesario.  Señalar que el nombre base de la descripción de fuente
  226.      se crea de éste distinguiendo entre mayúsculas y minúsculas. See
  227.      Descripcion fuente.
  228.  
  229. CTFILE
  230.      es el nombre del fichero traducción de catálogo que se leerá. Se
  231.      necesita para la creación de catálogos o la actualización de una
  232.      traducción de catálogo antigua usando el argumento NEWCTFILE:
  233.      FlexCat lee el fichero viejo y la descripción de catálogo, y crea un
  234.      fichero traducción de catálogo nuevo conteniendo las cadenas viejas
  235.      y, posiblemente, líneas vacías para las cadenas nuevas.
  236.  
  237. CATALOG
  238.      es el nombre del fichero catálogo que se creará. Este argumento
  239.      necesita que también se indique el argumento CDFILE.
  240.  
  241. NEWCTFILE
  242.      es el nombre del fichero traducción de catálogo que se creará.
  243.      FlexCat lee, si se dá, cadenas de CTFILE, y las cadenas que falten de
  244.      la traducción de catálogo se sustituyen con líneas vacías. (La
  245.      nueva traducción de catálogo sólo contendrá líneas vacías como
  246.      cadenas si se omite el CTFILE).
  247.  
  248. SOURCES
  249.      son los nombres de los ficheros de código fuente que se van a crear.
  250.      Se debería poner en forma de fuente=patrón donde fuente es el
  251.      fichero a crear y patrón es el nombre del fichero de descripción de
  252.      fuente que se analizará.
  253.  
  254.    Ver Vistazo para ejemplos de líneas de comandos.
  255.  
  256. Ficheros de descripción de catálogo
  257. ***********************************
  258.  
  259.    Un fichero descripción de catálogo contiene cuatro tipos de líneas.
  260.  
  261. Líneas de comentario
  262.      Cualquier linea que empieze por un punto y coma se supone una línea de
  263.      comentario, y por tanto se ignora. (Las siguientes líneas de cadena
  264.      son una excepción y pueden empezar con un punto y coma).
  265.  
  266. Líneas de comando
  267.      Cualquier línea que empieze con un '#' (con la misma excepción que
  268.      antes) se suponen líneas de comando. Los posible comandos son:
  269.     #language <cad>
  270.           indica el idioma por defecto del programa, el idioma de las
  271.           cadenas de la descripción de catálogo. Por defecto es #laguage
  272.           english.
  273.  
  274.     #version <num>
  275.           indica el número de versión de los catálogos a abrir. Señalar
  276.           que este número debe coincidir exactamente y no ser el mismo o
  277.           superior como en `Exec/Openlibrary'. Una excepción es el número
  278.           0, que acepta cualquier catálogo. El valor por omisión es
  279.           #versión 0. En Locale/OpenCatalog encontrarás más
  280.           información sobre el idioma del catálogo y la versión.
  281.  
  282.     #lengthbytes <num>
  283.           Indica a Flexcat que ponga el número de bytes dado antes de cada
  284.           cadena que contenga su longitud. La longitud es el número de
  285.           bytes de la cadena sin bytes de longitud ni el byte NUL del
  286.           final. (Los ficheros catálogo, y por tanto las cadenas del
  287.           catálogo siempre tendrán un byte NUL al final. Esto no siempre
  288.           es cierto para las cadenas por defecto, depende del fichero de
  289.           descripción de fuente).  <num> debe estar entre 0 y
  290.           sizeof(long)=4, por omisión es #lengthbytes 0.
  291.  
  292.     #basename <cad>
  293.           Pone el nombre-base de la descripción de fuente. See Descripcion
  294.           fuente.  Esto anula el nombre-base del argumento CDFILE de la
  295.           línea de comandos.  See Inicio del programa.  En los comandos no
  296.      se distinguen mayúsculas de minúscalas.
  297.  
  298. Líneas de descripción
  299.      declaran una cadena. Son de la forma IDCAD (id/longmin/longmax)
  300.      donde IDCAD es un identificador (cadena que consta de los caracteres
  301.      a-z,A-Z y 0-9), id es un número único (desde ahora lo llamaremos
  302.      ID), longmin y longmax son la longitud mínima y máxima
  303.      respectivamente de la cadena. Los tres últimos se pueden omitir
  304.      (¡aunque no los caracteres (//)!), en cuyo caso FlexCat elige un
  305.      número y no restringe la longitud de la cadena.  Lo mejor es no usar
  306.      los IDs si no los necesitas. Las líneas que las siguen son
  307.  
  308. Líneas de cadena
  309.      contienen la propia cadena y nada más. Pueden contener ciertos
  310.      caracteres de control que empiezan con una barra inversa:
  311.     \b
  312.           Borra atrás (Ascii 8)
  313.  
  314.     \c
  315.           CSI (Introductor de Sequencia de Control) (Ascii 155)
  316.  
  317.     \e
  318.           Escape (Ascii 27)
  319.  
  320.     \f
  321.           Salto página (Ascii 12)
  322.  
  323.     \g
  324.           Pitido pantalla (Ascii 7)
  325.  
  326.     \n
  327.           Salto de línea, (newline) (Ascii 10)
  328.  
  329.     \r
  330.           Retorno de Carro (Ascii 13)
  331.  
  332.     \t
  333.           Tabulador (Ascii 9)
  334.  
  335.     \v
  336.           Tabulador Vertical (Ascii 11)
  337.  
  338.     \)
  339.           El paréntesis final que puede necesitarse como parte de una
  340.           sequencia (..), ver Descripcion fuente.
  341.  
  342.     \\
  343.           La propia barra inversa.
  344.  
  345.     \xHH
  346.           El caracter dado por el código ASCII HH, donde HH son
  347.           dígitos hexadecimales.
  348.  
  349.     \OOO
  350.           El caracter dado por el código ASCII OOO, donde OOO son
  351.           dígitos octales.  Finalmente, una barra inversa sóla al final de
  352.      la línea provoca la concatenación con la siguente línea. Esto
  353.      permite usar cadenas de cualquier longitud, FlexCat no hace
  354.      suposiciones sobre la longitud de la cadena.
  355.  
  356.    Por tanto, una cadena se dá con una línea de descripción seguida de un
  357. línea de cadena. Veamos un ejemplo:
  358.          msgHola (/4/)
  359.          ¡Hola, esto es castellano!\n
  360.  
  361. Aquí se omite el ID, por lo que FlexCat elige un número apropiado. El
  362. número 4 indica a FlexCat que la cadena siguiente no debe tener menos de 4
  363. caracteres, y que puede ser de cualquier longitud. Mira en el fichero
  364. FlexCat.cd para más ejemplos.
  365.  
  366. Ficheros traducción de catálogo
  367. *******************************
  368.  
  369.    Los ficheros traducción de catálogo son bastante parecidos a las
  370. descripciones de catálogo, a excepción de comandos diferentes y por no
  371. tener información sobre el ID de cadena ni sobre la longitud. (Éstos se
  372. toman de la descripción de catálogo). Deben aparecer todas las cadenas de
  373. la descripción de catálogo, (sin embargo, FlexCat no escribe en el
  374. catálogo las cadenas que son idénticas a la cadena por omisión), y no
  375. debe tener identificadores adicionales. Esto se puede asegurar fácilmente
  376. si se usa FlexCat para crear las traducciones de catálogo nuevas. See
  377. Vistazo.
  378.  
  379.    Los comandos que se permiten en traducciones de catálogo son:
  380. ##version <cad>
  381.      Indica la versión del catálogo en forma de cadena de Versión de
  382.      AmigaDOS.  Ejemplo:
  383.               ##version $VER: English.ct 8.1 (22.05.94)
  384.      El número de versión de este catálogo es 8. De hecho, la versión
  385.      de la descripción de catálogo debe ser 0 u 8.
  386.  
  387. ##language <cad>
  388.      El idioma del catálogo. Por supuesto, debe ser otro idioma distinto
  389.      del idioma de la descripción de catálogo. Los comandos
  390.      ##language y ##version deben estar presentes en la traducción
  391.      de catálogo.
  392.  
  393. ##codeset <num>
  394.      Actualmente no se usa, debe ser 0. Este es el valor por defecto.
  395.  
  396.    La cadena de antes sería algo como lo siguiente en la traducción de
  397. catálogo:
  398.          msgHola
  399.          Hello, this is english!\n
  400.  
  401. Mira en Español.ct para más ejemplos de una traducción de catálogo.
  402.  
  403. Ficheros de descripción de fuente
  404. *********************************
  405.  
  406.    Esta es la parte especial de FlexCat. Hasta ahora no hay nada que no
  407. puedan ofrecer CatComp, KitCat u otros. El código fuente creado debe hacer
  408. fácil el uso de los catálogos sin perder flexibilidad. Debería poder
  409. utilizarse cualquier lenguaje de programación y debería poder
  410. satisfacerse cualquier requisito. Esto parece una contradición, pero la
  411. solución de FlexCat son los ficheros descripción de fuente que contienen
  412. un patrón del código fuente que se creará. Éstos son editables de la
  413. misma forma que lo son los ficheros descripción de catálogo y traducción
  414. de catálogo, por ello, FlexCat puede crear cualquier código.
  415.  
  416.    Se analizan las descripciones de fuente para encontrar ciertos símbolos
  417. que se substituyen por ciertos valores. Símbolos posibles son los
  418. caracteres de barra inversa anteriores y, además, secuencias que empiezen
  419. con %. (Esto lo conocen bien los programadores en C).
  420. %b
  421.      es el nombre base de la descripción de catálogo. See Inicio del
  422.      programa.
  423.  
  424. %v
  425.      es el número de versión de la descripción de catálogo. No lo
  426.      confundas con la cadena de versión de la traducción de catálogo.
  427.  
  428. %l
  429.      es el idioma de la descripción de catálogo. Señalar que ésta se
  430.      inserta como una cadena. Mira % más adelante.
  431.  
  432. %n
  433.      es el número de cadenas de la descripción de catálogo.
  434.  
  435. %%
  436.      es el propio caracter %.
  437.  
  438.    Pero lo más importante son las siguientes secuencias. Éstas
  439. representan a las cadenas del catálogo de diferentes formas. Las líneas
  440. que contienen uno o más de estos símbolos se repiten para cada cadena.
  441.  
  442. %i
  443.      es el identificador de la descripción de catálogo.
  444.  
  445. %d
  446.      es el ID de la cadena.
  447.  
  448. %s
  449.      es la propia cadena; se insertará dependiendo del lenguaje de
  450.      programación, y se puede controlar con los comandos ##stringtype y
  451.      ##shortstrings.
  452.  
  453. %(...)
  454.      inserta el texto entre los paréntesis en todas las cadenas menos en la
  455.      última. Esto se necesitará probablemente en vectores si las entradas
  456.      del vector se deben separar con comas pero la última no se debe
  457.      seguir con una coma. Señalar que entre los paréntesis no se
  458.      substituirán las secuencias %. Se permiten, sin embargo, las
  459.      secuencias de barra inversa.  Las secuencias de control %l y %s
  460. crean cadenas. Aunque la forma en que queden las cadenas depende del
  461. lenguaje de programación. Ese es el motivo de que la descripción de
  462. fuente permita líneas similares a las de la traducción de catálogo.
  463. Éstas deben empezar con el primer caracter de la línea y cada comando debe
  464. tener su propia línea. Los posibles comandos son:
  465. ##shortstrings
  466.      hace que las cadenas más largas se dividan en varias líneas. Esto no
  467.      siempre será posible o no estará implementado en FlexCat, y por
  468.      ello, la opción por defecto es crear sólo una cadena, probablemente,
  469.      bastante larga.
  470.  
  471. ##stringtype <tipo>
  472.      Indica a FlexCat cómo deben aparecer las cadenas. Los tipos posibles
  473.      son:
  474.     None
  475.           No se crean caracteres adicionales. Se inserta una imagen de la
  476.           cadena y nada más. No se pueden poner caracteres binarios (las
  477.           secuencias con barra inversa).
  478.  
  479.     C
  480.           crea cadenas de acuerdo con el C. Las cadenas se preceden y
  481.           finalizan con el caracter ". Las cadenas se dividen usando
  482.           secuencias "\ al final de la línea y " al principio de la
  483.           nueva línea. (La barra inversa se necesita en macros). Los
  484.           caracteres binarios se insertan usando \OOO. See C.
  485.  
  486.     Oberon
  487.           es como el tipo de cadena C, excepto por la barra final al final
  488.           de la línea.
  489.  
  490.     Assembler
  491.           Las cadenas se crean usando dc.b. Los caracteres ASCII legibles
  492.           se preceden y siguen con el caracter ', los caracteres binarios
  493.           se insertan como $XX. See Ensamblador.
  494.  
  495.     E
  496.           Las cadenas se preceden y siguen con el caracter '. Un +
  497.           concatena cadenas que se reparten por varias líneas. Los
  498.           caracteres binarios se insertan de la misma forma que en C.
  499.  
  500.    Veamos un fragmento del fichero C_h.sd creando un fichero include para
  501. el lenguaje de programación C.
  502.      ##stringtype C
  503.      ##shortstrings
  504.      
  505.      #ifndef %b_CAT_H    /* Nos aseguramos de que sólo se lea una vez. */
  506.      #define %b_CAT_H
  507.      
  508.      /*  Leemos los demás includes */
  509.      #include <exec/types.h>
  510.      #include <libraries/locale.h>
  511.      
  512.      /*  Prototipos    */
  513.      extern void Open%bCatalog(struct Locale *, STRPTR);
  514.      extern void Close%bCatalog(void);
  515.      extern STRPTR Get%bString(LONG);
  516.      
  517.      /*  Definiciones de los identificadores y sus IDs. */
  518.      /*  Esta línea se repetirá para cada cadena.       */
  519.      #define %i %d
  520.      
  521.      #endif
  522.  
  523. Incluyendo fuentes de FlexCat en programas propios
  524. **************************************************
  525.  
  526.    Por supuesto, esto depende del tipo de código fuente que se desee crear,
  527. y por tanto de la descripción de fuente. De lo que estamos hablando aquí
  528. es de los ficheros descripción de fuente que se distribuyen con FlexCat.
  529. See Descripcion fuente.
  530.  
  531.    Todas las descripciones de fuente deberían permitir el uso del programa
  532. sin la locale.library. Sin embargo, debe estar presente una variable
  533. llamada LocaleBase (_LocaleBase para ensamblador) e inicializarse con
  534. NULL o con una llamada a `Exec/OpenLibrary'. En el primer caso no es
  535. posible la localización a no ser que se use el fichero de descripción de
  536. fuente C_c_V20.sd. Éste permite la localización bajo 2.0 sustituyendo
  537. la locale.library por la iffparse.library. (Para ello debe estar
  538. presente e inicializada una variable IFFParseBase como con
  539. LocaleBase). See C. El programador no necesita conocer estas
  540. librerías a no ser que quiera crear sus propias descripciones de fuente.
  541.  
  542.    Hay tres funciones, y llamarlas es bastante sencillo.
  543.  
  544.  - : OpenCatalog (locale, idioma)
  545.      Esta función probablemente abrirá el catálogo. El argumento
  546.      locale es un puntero a la estructura Locale y idioma es una
  547.      cadena que contiene el nombre del idioma que se debería abrir. En la
  548.      mayoría de los casos deberían ser ambos NULL o NIL,
  549.      respectivamente, ya que en otro caso se anulan los valores que
  550.      predefine el usuario. Para más detalles mira en `Locale/OpenCatalog'.
  551.  
  552.      Si el usario tiene español y Deutsch como idiomas por omisión y
  553.      el nombre base del programa es XXX, buscará los siguientes ficheros:
  554.               PROGDIR:Catalogs/español/XXX.catalog
  555.               LOCALE:Catalogs/español/XXX.catalog
  556.               PROGDIR:Catalogs/Deutsch/XXX.catalog
  557.               LOCALE:Catalogs/Deutsch/XXX.catalog
  558.  
  559.      donde PROGDIR: es el directorio actual del programa. (Se puede
  560.      cambiar el orden de PROGDIR: y LOCALE: para evitar los requeters
  561.      del tipo Inserta volumen YYY.
  562.  
  563.      OpenCatalog es de tipo void (para programadores en Pascal un
  564.      procedimiento) y por tanto no devuelve nada.
  565.  
  566.  - : GetString (ID)
  567.      Devuelve un puntero a la cadena con ese ID de la descripción de
  568.      catálogo.  Por supuesto estas cadenas son propiedad de
  569.      locale.library y no se deben modificadar.
  570.  
  571.      Podría ser útil un ejemplo. Cojamos la cadena de la descripción de
  572.      catálogo del ejemplo, que se llamaba msgHola. Las descripciones de
  573.      fuente declaran una cosntante msgHola representando el ID. Se
  574.      podría imprimir en C usando:
  575.               printf("%s\n", GetString(msgHola));
  576.  
  577.  - : CloseCatalog (void)
  578.      Esta función libera el catálogo (que está reservado en RAM) antes de
  579.      terminar el programa. Puedes llamar a esta fucnión en cualquier
  580.      momento, incluso antes de llamar a OpenCatalog.
  581.  
  582. Fuentes de FlexCat en programas en C
  583. ====================================
  584.  
  585.    El fuente en C cosiste en dos partes: Un fichero .c que debería
  586. compilar y linkar sin problemas, y un fichero include que debería
  587. incluirse desde cualquier parte del fuente que use cadenas de catálogo y
  588. el cual define los IDs como macros.
  589.  
  590.    Hay dos versiones diferentes para la parte .c: C_c_V21.sd es un
  591. versión bastante simple usando las funciones correspondientes de la
  592. locale.library y que permite la localización a partir del Workbench
  593. 2.1. Por otro lado la C_c_V20.sd substituye la locale.library con la
  594. iffparse.library si la primera no está disponible y lo está la útlima.
  595. Esto permite la localización para el Workbench 2.0 también. Los programas
  596. que usen ésta deberían tener una opción Idioma y dar el argumento
  597. correspondiente a OpenCatalog. Esta opción no se debería usar en 2.1 y
  598. posteriores, y por ello el argumento de idioma de OpenCatalog debería
  599. seguir siendo NULL.
  600.  
  601.    Por supuesto, sería posible escribir una tercera versión usando
  602. catálogos con Ansi-C, pero no quiero soportar la 1.3 más.
  603.  
  604.    Para diferenciar las funciones OpenCatalog y CloseCatalog de las
  605. funciones respectivas de Locale con los mismos nombres, y para permitir
  606. diferentes catálogos en un mismo programa, las funciones de FlexCat
  607. obtienen nombres ligeramente modificados: OpenXXXCatalog y
  608. CloseXXXCatalog, donde XXX es el nombre base de la descripción de
  609. fuente. El concepto ha sido copiado de GadToolsBox y, según creo, parece
  610. bueno. See Descripcion fuente.
  611.  
  612.    Los prototipos de las funciones son:
  613.          void OpenXXXCatalog(struct Locale *loc, char *idioma);
  614.          STRPTR GetXXXString(ULONG);
  615.          void CloseXXXCatalog(void);
  616.  
  617.    Mira en HolaMundoLocal.c para ver un ejemplo. (see Vistazo)
  618.  
  619. Fuentes de FlexCat en programas en Oberon
  620. =========================================
  621.  
  622.    Hay dos descripciones de fuentes diferentes: Oberon_V38.sd crea el
  623. fuente usando Locale.mod de Harmut Goebel. Oberon_V39.sd crea el fuente
  624. usando el Locale.mod distribuido con AmigaOberon.
  625.  
  626.    Los prototipos de las funciones son:
  627.          XXX.OpenCatalog(loc: Locale.LocalePtr; idioma : ARRAY OF CHAR);
  628.          XXX.GetString(num: LONGINT): Exec.StrPtr;
  629.          XXX.CloseCatalog();
  630.  
  631. donde XXX es el nombre base de la descripción de fuente.  See
  632. Descripcion fuente.
  633.  
  634.    Finalmente veamos un ejemplo de fuente de FlexCat:
  635.          MODULE HolaMundoLocal;
  636.      
  637.          IMPORT  x:=HolaMundoLocal_Cat; Dos;
  638.      
  639.          BEGIN
  640.            x.OpenCatalog(NIL, "");
  641.      
  642.            Dos.PrintF("%s\n", x.GetString(x.msgHola));
  643.            (* El catálogo se cerrará automáticamente  *)
  644.            (* al finalizar el programa.               *)
  645.          END CualquierCosa;
  646.  
  647. Fuente de FlexCat en programas en ensamblador
  648. =============================================
  649.  
  650.    El fuente en ensamblador se crea para usarlo con el ensamblador de Aztec.
  651. No debría ser muy diferente a otros ensambladores y deberías ser capaz de
  652. implementar descripciones de fuente propias. El fuente consiste de dos
  653. partes: Un fichero .asm que debería ensamblarse    y linkarse sin problemas,
  654. y un fichero include .i que define los IDs de las cadenas y debe
  655. incluirse en el porgrama que las use.
  656.  
  657.    Como siempre, el resultado de la función se da en d0, y las funciones
  658. guardan los registros d2-d7 y a2-a7. OpenCatalog espera sus argumentos en
  659. a0 (un puntero a una estructura Locale) y a1 (puntero a la cadena del
  660. idioma), que deberían ser NULL en la mayoría de los casos. GetString
  661. espera un puntero en a0.
  662.  
  663.    Finalmente, veamos un programa de ejemplo usando fuentes de FlexCat:
  664.      *   HolaMundoLocal.asm
  665.          include "XXX.i" ; Es obligatorio abrirlo. Contiene
  666.                  ; "xref OpenHolaMundoLocalCatalog", ...
  667.          xref    _LVOOpenLibrary
  668.          xref    _LVOCloseLibrary
  669.          xref    _AbsExecBase
  670.      
  671.          dseg
  672.      LocNam: dc.b    "locale.library",0
  673.          dc.l    _LocaleBase,4    ; Debe estar con este nombre
  674.      
  675.          cseg
  676.      main:     move.l  #38,d0     ; Abre la locale.library
  677.          lea LocName,a1
  678.          move.l  _AbsExecBase.a6
  679.          jsr _LVOOpenLibrary(a6)
  680.      *   NO salir si falla OpenLibrary
  681.          sub.l   a0,a0        ; Abre el catálogo
  682.          sub.l   a1,a1
  683.          jsr OpenHolaMundoLocalCatalog
  684.      
  685.          lea.l   msgHola,a0        ; Obtiene puntero a la cadena
  686.          jsr GetHolaMundoLocalString
  687.          jsr PrintD0         ; y la imprime
  688.      
  689.      Final:
  690.          jsr CloseHolaMundoLocalCatalog ; Cierra el Catálogo
  691.          move.l  _LocaleBase,a1       ; Cierra la locale.library
  692.          move.l  a1,d0           ; este test es necesario para 1.3
  693.          beq Final1
  694.          jsr CloseLibrary
  695.      Final1:
  696.          rts
  697.          end
  698.  
  699. Fuentes de FlexCat en programas en E
  700. ====================================
  701.  
  702.    E se diferencia drásticamente de otros lenguajes de programación en un
  703. punto: No puedes compilar módulos separados y luego linkarlos juntos. Todo
  704. el código fuente debe estar en un fichero. La mejor solución a este
  705. problema es usar EPP de Barry Wills. (Origen: Aminet, directorio dev/e,
  706. disco de Fred Fish). Esto te permite integrar los fuentes creados con la
  707. descripción de fuente E21b.sd en una línea:
  708.          PMODULE 'xxx_cat'
  709.  
  710. donde xxx es el nombre-base de tu aplicación. Sin EPP necesitas insertar
  711. el fuente de FlexCat manualmente en tu propio fuente. Debes insertar el
  712. fuente después de tus propias definiciones, y antes del primer
  713. procedimiento. (De otra forma estarías obligado a crear e insertar más de
  714. un fichero con código fuente de FlexCat).
  715.  
  716.    Las funciones get_xxx_string, open_xxx_catalog y
  717. close_xxx_catalog están en el código fuente creado. (Estos nombres
  718. ligeramente modificados se necesitan para permitir catálogos diferentes en
  719. un mismo programa). Señalar que (al contrario que en C, por ejemplo) ¡no
  720. debes llamar a get_xx_string antes de open_xx_catalog!
  721.  
  722.    Un HolaMundoLocal.e usando EPP podría parecerse a:
  723.          /*    HolaMundoLocal.e  */
  724.      
  725.          PMODULE holamundolocal_cat
  726.      
  727.          PROC main()
  728.          /*    Abre Locale.library; ¡No salir, si falla!  */
  729.          localebase := OpenLibrary('locale.library', 0)
  730.      
  731.          /*    Abre el fichero catálogo.                */
  732.          open_holamundolocal_catalog(NIL, NIL)
  733.      
  734.          WriteF('\s\n', get_holamundolocal_string(MSG_HOLA_MUNDO))
  735.      
  736.          close_holamundolocal_catalog()
  737.          ENDPROC
  738.  
  739. Próximo desarrollo de FlexCat
  740. *****************************
  741.  
  742.    No espero mucho más desarrollo de FlexCat porque que pienso que ya es
  743. bastante completo. Por supuesto, estoy abierto a sugerencias, trucos o
  744. críticas. Especialmente, me ofrezco a incluir nuevos tipos de cadenas, ya
  745. que ésto se puede hacer con cambios mínimos.
  746.  
  747.    Estaría muy agradecido si me enviarais cualquie nueva descripcione de
  748. fuente para poder incluirlas en próximas distribiciones. Cualquier
  749. lenguaje de programación, cualquier extensión, siempre y cuando se haya
  750. comprobado bien el código fuente en un programa real. Tambien apreciaría
  751. recibir nuevos catálogos. Es suficiente insertar las cadenas en el fichero
  752. NewCatalogs.ct que es parte de la distribución.
  753.  
  754. Créditos
  755. ********
  756.  
  757.    Agradezco especialmente a:
  758. Albert Weinert
  759.      por KitCat, el predecesor de FlexCat que me hizo grandes cosas, pero
  760.      que finalmente no era lo suficientemente flexible.
  761.  
  762. Reinhard Spisser und Sebastiano Vigna
  763.      por la versión de texinfo para Amiga. Esta documentación está
  764.      escrita utilizándolo. (La traducción también :-)).
  765.  
  766. The Free Software Foundation
  767.      por la versión original de texinfo y muchas otras excelentes cosas.
  768.  
  769. Matt Dillon
  770.      por DICE y especialmente por DME.
  771.  
  772. Alessandro Galassi
  773.      por el catálogo italiano.
  774.  
  775. Lionel Vintenat
  776.      por la descripción de fuente de E y su documentación, los catálogos
  777.      en francés y por informar sobre errores.
  778.  
  779. The people of #AmigaGer
  780.      por contestarme muchas preguntas estúpidas, y por la diversión, por
  781.      ejemplo stefanb (Stefan Becker), PowerStat (Kai Hoffmann), \ ill
  782.      (Markus Illenseer), Quarvon (Jürgen Lang), ZZA (Bernhard Möllemann),
  783.      Tron (Mathias Scheler), mungo (Ignatios Souvlatzis), \ jow (Jürgen
  784.      Weinelt) und Stargazer (Petra Zeidler).
  785.  
  786. Commodore
  787.      por el Amiga y el Kickstart 2.0. Seguid desarrollando sobre él y
  788.      siguiré siendo un usuario de Amiga durante los próximos 8 años. ;-)
  789.  
  790.    La traducción a castellano de este manual, así como de los catálogos
  791. del programa han sido realizados por:
  792.            Antonio Joaquín Gomez Gonzalez
  793.            C/ Venezuela, 14 - 2 I
  794.            33213 Gijon - Asturias (ESPAÑA)
  795.            E-mail: u0868551@oboe.etsiig.uniovi.es (mínimo hasta Sept. 94)
  796.  
  797. Índice
  798. ******
  799.  
  800.  
  801.  
  802.  .cd                                    Descripcion de catalogo
  803.  .ct                                    Traduccion de catalogo
  804.  .sd                                    Descripcion fuente
  805.  Autor                                  Renuncias
  806.  AztecAs_asm.sd                         Ensamblador
  807.  AztecAs_i.sd                           Ensamblador
  808.  C                                      C
  809.  Caracteres de control                  Descripcion de catalogo
  810.  CLI                                    Inicio del programa
  811.  Codigo-ASCII                           Descripcion de catalogo
  812.  Contribuciones                         Futuro
  813.  Creditos                               Creditos
  814.  C_c_V20.sd                             C
  815.  C_c_V21.sd                             C
  816.  C_h.sd                                 C
  817.  Derechos                               Renuncias
  818.  Descripcion de catalogo                Descripcion de catalogo
  819.  Descripcion de fuente                  Descripcion fuente
  820.  Dirección                             Renuncias
  821.  Distribución                          Renuncias
  822.  E                                      E
  823.  E21b.sd                                E
  824.  E21b_defs.sd                           E
  825.  E21b_procs.sd                          E
  826.  English.ct                             Traduccion de catalogo
  827.  Ensamblador                            Ensamblador
  828.  EPP                                    E
  829.  FlexCat                                Futuro
  830.  FlexCat.cd                             Descripcion de catalogo
  831.  Fuentes FlexCat                        Usando fuentes FlexCat
  832.  Futuro                                 Futuro
  833.  Instalación                           Instalacion
  834.  Internet                               Renuncias
  835.  Mail                                   Renuncias
  836.  Oberon                                 Oberon
  837.  Oberon_V38.sd                          Oberon
  838.  Oberon_V39.sd                          Oberon
  839.  Permisos                               Renuncias
  840.  Prohibiciones                          Renuncias
  841.  Requisitos                             Instalacion
  842.  Traduccion de catalogo                 Traduccion de catalogo
  843.  Usando fuentes FlexCat                 Usando fuentes FlexCat
  844.  Vistazo                                Vistazo
  845.  Workbench                              Inicio del programa
  846.  
  847.